"""
Twilio python REST and XML response helper library

Copyright (c) 2009 Twilio, Inc.

Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following
conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.
"""

__author__ = 'phy@twilio.com (Evan Cooke)'

import urllib, urllib2, base64, cgi
from xml.dom import minidom

try:
    from google.appengine.api import urlfetch
    APPENGINE = True
except:
    APPENGINE = False

# Twilio types
MAN = 'man'
WOMAN = 'woman'

GET = 'GET'
POST = 'POST'

CONTINUE = 'continue'
HANGUP = 'hangup'

_TWILIO_API_URL = 'https://api.twilio.com/2008-08-01/Accounts/'

class TwilioException(Exception):
    pass

class HTTPErrorProcessor(urllib2.HTTPErrorProcessor):
    def https_response(self, request, response):
        code, msg, hdrs = response.code, response.msg, response.info()
        if code >= 300:
            response = self.parent.error(
                'http', request, response, code, msg, hdrs)
        return response

class HTTPErrorAppEngine(Exception): pass

class Account:
    """Twilio account object.  Can be used to initiate outgoing calls, ....
    """
    def __init__(self, id, token):
        """initialize a twilio account object
        
        id: Twilio account SID/ID
        token: Twilio account token
        
        returns a Twilio account object
        """
        self.id = id
        self.token = token
        self.opener = None
    
    def _parse_resp_call(self, dom, d):
        calls = dom.getElementsByTagName('Call')
        if not calls:
            return d
        for c in calls:
            for e in c.childNodes:
                if e.firstChild:
                    d[e.tagName] = e.firstChild.data
    
    def _parse_resp(self, resp):
        d = {}
        dom = minidom.parseString(resp)
        self._parse_resp_call(dom, d)
        return d
    
    def _urllib2_post(self, uri, params):
        # install error processor to handle HTTP 201 response correctly
        if self.opener == None:
            self.opener = urllib2.build_opener(HTTPErrorProcessor)
            urllib2.install_opener(self.opener)
        
        req = urllib2.Request(uri, urllib.urlencode(params))
        authstring = base64.encodestring('%s:%s' % (self.id, self.token))
        authstring = authstring.replace('\n', '')
        req.add_header("Authorization", "Basic %s" % authstring)
        
        response = urllib2.urlopen(req)
        return self._parse_resp(response.read())
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        
    def _appengine_post(self, uri, params):
        authstring = base64.encodestring('%s:%s' % (self.id, self.token))
        authstring = authstring.replace('\n', '')
        r = urlfetch.fetch(url=uri, payload=urllib.urlencode(params),
            method=urlfetch.POST,
            headers={'Content-Type': 'application/x-www-form-urlencoded',
                'Authorization': 'Basic %s' % authstring})
        if r.status_code >= 300:
            raise HTTPErrorAppEngine("HTTP %s: %s" % \
                (r.status_code, r.content))
        return self._parse_resp(r.content)
    
    def initiate_call(self, called, url, caller=None, method=None, 
        sendDigits=None, debug=False, ifMachine=None, timeout=None):
        """Initiate an outgoing call
        
        called: phone number to call (string)
        url: complete url of call handler (string)
        caller: caller ID (string)
        method: submit to 'url' using GET or POST (Twilio type)
        sendDigits: keys to dial after connecting to the number (string)
        debug: set debug mode on this call (bool)
        ifMachine: if answering machine CONTINUE or HANGUP (Twilio type)
        timeout: number seconds to ring before returning 'no-answer' (int)
        
        returns dict() of Twilio call response variables
        """
        if method and (method != GET and method != POST):
            raise TwilioException( \
                "Invalid method parameter, must be GET or POST")
        if ifMachine and (ifMachine != CONTINUE and ifMachine != HANGUP):
            raise TwilioException( \
                "Invalid ifMachine parameter, must be CONTINUE or HANGUP")
        
        fields = { 'Called': called, 'Url': url }
        if caller: fields['Caller'] = caller
        if method: fields['Method'] = method
        if sendDigits: fields['SendDigits'] = sendDigits
        if debug: fields['Debug'] = 'true'
        if ifMachine: fields['IfMachine'] = ifMachine
        if timeout: fields['Timeout'] = timeout
        
        uri = _TWILIO_API_URL + self.id + '/Calls'
        if APPENGINE:
            return self._appengine_post(uri, fields)
        return self._urllib2_post(uri, fields)

class Verb:
    """Twilio basic verb object.
    """
    def __init__(self, tag, body):
        self.tag = tag
        self.body = body
        self.verbs = []
        self.attrs = {}
    
    def append(self, verb):
        if not verb:
            return
        self.verbs.append(verb)
    
    def __repr__(self):
        s = '<%s' % self.tag
        for a in self.attrs:
            s += ' %s="%s"' % (a, self.attrs[a])
        if self.body or len(self.verbs) > 0:
            s += '>'
            if self.body:
                s += self.body
            if len(self.verbs) > 0:
                s += '\n'
                for v in self.verbs:
                    s += '\t\t' + str(v)
                s += '\t'
            s += '</%s>\n' % self.tag
        else:
            s += ' />\n'
        return s

class Say(Verb):
    """Say text
    
    text: text to say (string)
    voice: MAN or WOMAN (Twilio type)
    loop: number of time to say this text (int)
    """
    def __init__(self, text, voice=None, loop=None):
        Verb.__init__(self, 'Say', text)
        if voice and (voice != MAN and voice != WOMAN):
            raise TwilioException( \
                "Invalid voice parameter, must be MAN or WOMAN")
        if voice: self.attrs['voice'] = voice
        if loop: self.attrs['loop'] = loop
    
    def append(self, verb):
        raise TwilioException("'Say' is not nestable")

class Play(Verb):
    """Play audio file at a URL
    
    url: url of audio file, MIME type on file must be set correctly (string)
    loop: number of time to say this text (int)
    """
    def __init__(self, url, loop=None):
        Verb.__init__(self, 'Play', url)
        if loop: self.attrs['loop'] = loop
    
    def append(self, verb):
        raise TwilioException("'Play' is not nestable")

class Gather(Verb):
    """Gather digits from the caller's keypad
    
    action: URL to which the digits entered will be sent (string)
    method: submit to 'action' url using GET or POST (Twilio type)
    numDigits: how many digits to gather before returning (int)
    timeout: wait for this many seconds before returning (int)
    finishOnKey: key that triggers the end of caller input (string)
    """
    def __init__(self, action=None, method=None, numDigits=None, timeout=None,
        finishOnKey=None):
        Verb.__init__(self, 'Gather', None)
        if method and (method != GET and method != POST):
            raise TwilioException( \
                "Invalid method parameter, must be GET or POST")
        if action: self.attrs['action'] = action
        if method: self.attrs['method'] = method
        if numDigits: self.attrs['numDigits'] = numDigits
        if timeout: self.attrs['timeout'] = timeout
        if finishOnKey: self.attrs['finishOnKey'] = finishOnKey
    
    def append(self, verb):
        if not verb:
            return
        if not isinstance(verb, Say) and not isinstance(verb, Play):
            raise TwilioException( \
                "Can only nest 'Play' and 'Say' inside 'Gather'")
        Verb.append(self, verb)

class Number(Verb):
    """Specify phone number in a nested Dial element.
    
    sendDigits: keys to dial after connecting to the number (string)
    """
    def __init__(self, number, sendDigits=None):
        Verb.__init__(self, 'Number', number)
        if sendDigits: self.attrs['sendDigits'] = sendDigits
    
    def append(self, verb):
        raise TwilioException("'Number' is not nestable")

class Dial(Verb):
    """Dial another phone number and connect it to this call
    
    action: submit the result of the dial to this URL (string)
    method: submit to 'action' url using GET or POST (Twilio type)
    """
    def __init__(self, number=None, action=None, method=None):
        if number and len(number.split(',')) > 1:
            Verb.__init__(self, 'Dial', None)
            for n in number.split(','):
                self.append(Number(n.strip()))
        else:
            Verb.__init__(self, 'Dial', number)
        if method and (method != GET and method != POST):
            raise TwilioException( \
                "Invalid method parameter, must be GET or POST")
        if action: self.attrs['action'] = action
        if method: self.attrs['method'] = method
    
    def append(self, verb):
        if not verb:
            return
        if not isinstance(verb, Number):
            raise TwilioException("only'Number' can be nested in a 'Dial'")
        Verb.append(self, verb)

class Record(Verb):
    """Record audio from caller
    
    action: submit the result of the dial to this URL (string)
    method: submit to 'action' url using GET or POST (Twilio type)
    maxLength: maximum number of seconds to record
    timeout: seconds of silence before considering the recording complete
    transcribe: True/False whether to perform speech-to-text transcription
    transcribeCallback: callback URL for transcription response (string)
    """
    def __init__(self, action=None, method=None, maxLength=None, 
        timeout=None, transcribe=None, transcribeCallback=None):
        Verb.__init__(self, 'Record', None)
        if method and (method != GET and method != POST):
            raise TwilioException( \
                "Invalid method parameter, must be GET or POST")
        if action: self.attrs['action'] = action
        if method: self.attrs['method'] = method
        if maxLength: self.attrs['maxLength'] = maxLength
        if timeout: self.attrs['timeout'] = timeout
        if transcribe != None: 
            if transcribe: self.attrs['transcribe'] = "true"
            else: self.attrs['transcribe'] = "false"
        if transcribeCallback:
            self.attrs['transcribeCallback'] = transcribeCallback
    
    def append(self, verb):
        raise TwilioException("'Record' is not nestable")

class Redirect(Verb):
    """Redirect call flow to another URL
    
    url: url of call handler (string)
    """
    def __init__(self, url):
        Verb.__init__(self, 'Redirect', url)
    
    def append(self, verb):
        raise TwilioException("'Redirect' is not nestable")

class Hangup(Verb):
    """Hangup the call
    """
    def __init__(self):
        Verb.__init__(self, 'Hangup', None)
    
    def append(self, verb):
        raise TwilioException("'Hangup' is not nestable")

class Response:
    """Twilio response object.
    """
    def __init__(self):
        self.verbs = []
    
    def append(self, verb):
        if isinstance(verb, Number):
            raise TwilioException("'Number' can only be nested in a 'Dial'")
        if verb:
            self.verbs.append(verb)
    
    def __repr__(self):
        s = '<Response>'
        if len(self.verbs) > 0:
            s += '\n'
            for v in self.verbs:
                s += '\t' + str(v)
        s += '</Response>'
        return s
